home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / espool.com / ESPOOLER.DOC < prev    next >
Encoding:
Text File  |  1990-12-21  |  18.9 KB  |  421 lines
  1.    This software is NOT freeware, and is distributed under the shareware
  2.      concept, the fee requested for useage of this software is discussed
  3.      at the end of this file (very reasonable).
  4.    It is requested that this archive be distributed as a whole,
  5.      and that all files herein be kept together.
  6.    No fee should be charged for this software beyond actual distribution
  7.      costs (connect fees, diskette costs), and should in no case exceed $10.
  8.  
  9.  
  10.    What you should find in this archive:
  11.  
  12.        ESPOOLER.DOC    17098 bytes      This file.
  13.        TP55SPL.TPU     17344 bytes      Turbo Pascal 5.5 compatable unit.
  14.        TP50SPL.TPU     18192 bytes      Turbo Pascal 5.0 compatable unit.
  15.        SPLTEST.PAS      2443 bytes      Sample program using the spooler.
  16.        SPLTEST.EXE     12560 bytes      Executable version of same.
  17.  
  18.  
  19.  
  20.  SUMMARY:
  21.      This unit implements a text file device driver (TFDD) called 'SPL'
  22.    which is designed to allow Turbo Pascal 4.0-5.5 programs to dump
  23.    text to the printer as is normally done using the 'LST' TFDD found
  24.    in the 'printer' unit which is part of Turbo Pascal, but
  25.    without arresting the operation of the program entirely until the
  26.    printing is finished.  It has been tested with Espon LX/MX/FX
  27.    printers.  By default it uses only a 16K main memory buffer, which
  28.    should be fine for most text documents of 3 pages.  If you try and
  29.    dump more than that at a time you'll have to wait. Alternatively you
  30.    can expand the main memory spooler buffer up to 65521 bytes.  If you
  31.    have Expanded, or Extended memory on your computer, and the appropriate
  32.    memory manager you can install a spooler in EMS or XMS.  It can be any
  33.    size from 16K up to all of your EMS/XMS memory, at your discretion.
  34.  
  35.  
  36.   As indicated above there are actually 4 modes in which the spooler can
  37.    operate:
  38.  
  39.     1) The default, put the spooler buffer in main memory on the Turbo
  40.        Pascal heap.  This spooler buffer can be any size between 16384 bytes
  41.        and 65521 bytes (the largest single object that can be allocated on
  42.        the TP heap).
  43.  
  44.     2) If expanded memory is available, and a LIM 3.X compatible memory
  45.        manager which supports data aliasing is loaded, then a spooler buffer
  46.        between 16K and all the available expanded memory can be set up.
  47.  
  48.     3) If extended memory is available, and an XMS 2.0 compatible memory
  49.        manager (like HIMEM.SYS from Microsoft, or some versions QEMM-386
  50.        from Quarterdeck, and 386^MAX from Qualitas) then a spooler buffer
  51.        of between 16K and all the available extended memory can be set up.
  52.  
  53.     4) If expanded and extended memory are not available, and regular
  54.        memory is scarce, then the spooler can be directed to dump
  55.        characters directly to the printer, as is normally done when
  56.        writing to Turbo Pascal's LST printer device.
  57.  
  58.   It should be noted that first pausing the spooler's printing out and
  59.    then overflowing the spooler buffer will likely lock up the system,
  60.    so if you pause the spooler, don't feed it any more text.
  61.  
  62.   If a print screen is in progress then this spooler will wait until it's
  63.    finished before accepting any characters to print.  So DO NOT set
  64.    the printscr bit or the system will lock up.  Also printscr is disabled
  65.    while the spooler has characters in it's buffer.
  66.  
  67.   This unit opens the printer in non-text file mode, this allows values of
  68.     26 to be sent to the printer.  When the printer is opened with the
  69.     normal text file driver, all 26's (End of File marker's in DOS) are
  70.     automatically stripped off.  If we are dumping graphics, for example,
  71.     then this is obviously undesireable.
  72.  
  73.   This software does data aliasing when using expanded memory, and therefore
  74.     may not function with some types of software-only expanded memory
  75.     emulators.  (It should work on all 80386 specific expanded memory
  76.     emulators.)  This unit does however test for this capability and will
  77.     simply refuse to install the spooler in EMS if this capability is not
  78.     supported.  No function specific to the LIM 4.0 specification are used
  79.     so it should work with any LIM 3.X compatible memory manager.
  80.  
  81.   When using extended memory this software does not use the High Memory Area
  82.     which is available on many 80286 & 80386 based computers with more than
  83.     640K of memory.  It instead requires the availability of Extended Memory
  84.     Blocks which are beyond the HMA.  If EMB's are not supported the spooler
  85.     will refuse to load in extended memory.  This will return an I/O error
  86.     which can be trapped in the usual way.  Note: 8K of heap space is used
  87.     for a swap area when spooling in XMS.
  88.  
  89.   Sample useage:
  90.  
  91.     Writeln(SPL,'This is a test string.');
  92.     Writeln(SPL,'This is a combo of variables',Variable,' and strings.');
  93.     Writeln(SPL,#10#10,'This will give a couple of extra linefeeds.');
  94.  
  95. ----------------------------------------------------------------------------
  96.  
  97.   The externally visible procedures comprising this unit are:
  98.  
  99.    'SETPRINTER' - Allows you to change which printer the spooler will
  100.      send characters to, the default is LPT1.  To change to LPT2:
  101.  
  102.             SetPrinter(2);
  103.  
  104.  
  105.    'ALTERSPOOLERSIZE' - Allows you to change the default 16k spooler size.
  106.      This function has no effect unless the spooler device is closed. To
  107.      change the spooler size to 32k:
  108.  
  109.             Close(SPL);                    (* close spooler         *)
  110.             AlterSpoolerSize(32768);       (* increase spooler size *)
  111.             Rewrite(SPL);                  (* reopen spooler        *)
  112.  
  113.  
  114.    'SPOOLFUNCS' - Allows the program to directly manupulate the workings
  115.       of the spooler. It accepts an integer corresponding to the desired
  116.       function.
  117.      1: Clear the spooler.  This clears the contents of the spooling
  118.           queue, and stops the printing.
  119.      2: Pause the spooler.  This clauses the spooler to stop printing until
  120.           the 'Resume' function (function 3) is used.  This may be useful if
  121.           you are doing something that is time critical and/or should not be
  122.           interrupted until finished.  This has no effect if the spooling
  123.           is disabled (ie., printing directly to the printer).
  124.      3: Resume printing.  This cancels the pause caused by function 2.
  125.  
  126.  
  127.    'SPOOLERSTATUS' - Allows the program to query the status of the spooler.
  128.       Using the 'SplStatType' declared in this unit's interface section,
  129.       the current size of the spooler can be determined (a size of 0
  130.       indicating either that the spooler is closed, or that the spooler
  131.       is operating in the direct to printer mode (see description of
  132.       operational modes and how to change them below).  The number of bytes
  133.       left in the spooler buffer to print can be ascertained.  Finally whether
  134.       the spooler is currently paused or not can be determined.  Also what
  135.       mode the spooler is operating in can be determined.
  136.       NOTE:  The correct mode will be returned only if the spooler is open
  137.       when this procedure is called.
  138.  
  139.    'SET_SPOOLER_PRIORITY' - Changes the speed at which characters are dumped
  140.       out the parallel port.  The default priority, 0, sends about 50
  141.       characters a second to the parallel port and uses about 6-9% of the
  142.       CPU's clock cycles, this is Ok for most line printers.  The highest
  143.       priority, 10, sends about 200 characters a second to the parallel
  144.       port, and consumes about 18-21% of the CPU's clock cycles, this
  145.       highest priority will only have a visible effect on printers with
  146.       large internal print buffers, like laser printers.
  147.  
  148.    The following four procedures/functions change the operating mode of
  149.     the spooler.  The spooler device which is by default open, must be closed
  150.     for any of the following to have any effect.
  151.  
  152.    'DIRECT_TO_PRINTER' - Changes the mode in which the spooler will be opened
  153.      from the current mode, to direct to printer output.  This Procedure
  154.      will have no effect if the spooler device is not closed.
  155.      EXAMPLE : If for some reason you don't want the spooler taking up main
  156.      memory, ie., you need every byte of heap space you can get your hands
  157.      on. You can close the spooler down, change the spooler to direct to
  158.      printer operation, and reopen it:
  159.  
  160.                     Close(SPL);
  161.                     Direct_To_Printer;
  162.                     Rewrite(SPL);
  163.  
  164.      This will deallocate the spooler buffer, and cause any characters
  165.      sent to the spooler to go straight to the printer instead of into the
  166.      spooler buffer.  ie., calling:
  167.  
  168.                     Writeln(SPL,' ..... ');
  169.  
  170.      will have the same effect as:
  171.  
  172.                     Writeln(LST,' ..... ');
  173.  
  174.  
  175.    'SPOOL_IN_EMS' - Changes the mode in which the spooler will be opened
  176.      from the current mode to spooling in expanded memory.  It also specifies
  177.      the size of the expanded memory buffer desired.  This function checks
  178.      to see if there is an expanded memory manager loaded, if that EMM
  179.      supports data aliasing, and if enough expanded memory exists to support
  180.      the request.  If these conditions are met, then 0 is returned, otherwise
  181.      a value of 1 is returned, and the previously assigned spooler mode
  182.      remains operational. The EMS useage in this program saves and restores
  183.      the condition of the expanded memory manager before and after use, so it
  184.      should be compatable with programs that use EMS for other purposes.
  185.      This function will fail if the spooler device is not closed.
  186.      NOTE: Spooler size is rounded up to the next largest 16K block size.
  187.      EXAMPLE: I want to allocate a 32K spooler buffer in EMS:
  188.  
  189.                      Close(SPL);
  190.                      IF Spool_In_EMS(32768) = 0 THEN
  191.                        Rewrite(SPL);
  192.  
  193.    'SPOOL_IN_XMS' - Changes the mode in which the spooler will be opened
  194.      from the current mode to spooling in extended memory.  It also specifies
  195.      the size of the extended memory buffer desired.  This function checks
  196.      to see if there is an extended memory manager loaded, if that XMM
  197.      supports Extended Memory Blocks, and if enough expanded memory exists
  198.      to support the request.  If these conditions are met, then 0 is returned,
  199.      otherwise a value of 1 is returned, and the previously assigned spooler
  200.      mode remains operational.  This function will fail if the spooler device
  201.      is not closed.
  202.    NOTE: Spooler size is rounded up to the next largest 4K block size, with
  203.      a minimum of 16K.
  204.      EXAMPLE: I want to allocate a 32K spooler buffer in XMS:
  205.  
  206.                      Close(SPL);
  207.                      IF Spool_In_XMS(32768) = 0 THEN
  208.                        Rewrite(SPL);
  209.  
  210.  
  211.    'SPOOL_IN_MEMORY' - Changes the mode in which the spooler will be opened
  212.      from the current mode to spooling in main memory.  As indicated above
  213.      this procedure will have no effect if the spooler device is not closed.
  214.  
  215.  
  216.  
  217. ERROR Conditions:
  218.    If, when your program starts the spooler is printing direct to printer
  219.      then the spooler was unable to install itself normally.  What is
  220.      done in this case is any output normally directed through the spooler
  221.      is printed directly to the printer instead, as in "Direct_To_Printer".
  222.    Possible causes of this are:
  223.        1) There was insufficient heap space to install the default spooler.
  224.           If EMS is available you may still allocate an EMS buffer and
  225.           run in that fashion.  The remedies are : Free up some heap space,
  226.           or put the spooler in EMS or XMS.
  227.        2) More critical, a key DOS flag could not be located, and it was
  228.           unsafe to install the spooler.  There is no remedy for this.
  229.           Further attempts to open the spooler in any other mode will result
  230.           in an error condition.  This should not happen.
  231.  
  232.  
  233.    There are a number of cases where the calling one of the associated
  234.     spooler functions (Rewrite,Writeln,Write) can cause an error condition.
  235.     If you compile with I/O error checking off you'll be able to trap
  236.     these and prevent program termination.
  237.    Possible return codes which can occur are:
  238.  
  239.        Writeln,Write :
  240.                160 :  Out of paper, Device write fault.
  241.  
  242.        Rewrite:
  243.                1   :  Failure allocating EMS or XMS spooler.
  244.                 ( Only if you try to allocate the EMS or XMS spooler. )
  245.                203 :  If the spooler cannot allocate memory for it's buffer.
  246.                 ( Heap either too small or fragmented, main memory spooler. )
  247.  
  248.  
  249.  
  250.  
  251.  
  252.   The following is the interface for the spooler unit.
  253.   To compile this unit for Turbo Pascal 4.0 you will have to remove some
  254.         of the compiler directives which do not exist in TP 4.0.
  255.  
  256. {$A+,R-,S+,I+,D+,F-,V-,B-,N-,E-,L+,O-}
  257.  
  258. {--------------------------------------------------------------------}
  259. {---------------------------} INTERFACE {----------------------------}
  260. {--------------------------------------------------------------------}
  261.  
  262. uses CRT,DOS;
  263.  
  264. CONST
  265.   SplClear  = 1;     { Clear the spooler. }
  266.   SplPause  = 2;     { Pause the spooler's printing. }
  267.   SplResume = 3;     { Resume spooler printing. }
  268.  
  269. TYPE
  270.   SpoolWhereType = (DirectTOPrinter,InHeap,InEMS,InXMS);
  271.   SplStatType = RECORD
  272.                   SplSize : Longint;
  273.                   BytesToPrint : Longint;
  274.                   Paused : BOOLEAN;
  275.                   SpoolWhere : SpoolWhereType;
  276.                 END;
  277.  
  278.  
  279. VAR
  280.    SPL : TEXT;       { New text file. }
  281.  
  282.    Procedure SpoolFuncs(Operation : Integer);
  283.    Procedure SpoolerStatus(VAR Spoolstat : SplStatType);
  284.    Procedure SetPrinter(Port : BYTE);             { Change the printer spl sends to. }
  285.    Procedure AlterSpoolerSize(Size : LongInt);
  286.    Procedure Set_Spooler_Priority(NewPriority : WORD);
  287.  
  288.    Procedure Direct_To_Printer;                   { Select Mode of Spooler. }
  289.    Function  Spool_In_EMS(Size : LongInt):Integer;
  290.    Procedure Spool_In_Memory;
  291.    Function Spool_In_XMS(Size : LongInt): Integer;
  292.  
  293.  
  294. { END of interface }
  295.  
  296.  
  297.  
  298.  
  299. MORAL DOGMA
  300. ___________
  301.  
  302.  If you like this programming unit and find it useful, you are requested
  303. to support it's continued development, and the development of other
  304. useful programming tools for serious pascal developers by sending $10
  305. to the address below.  In addition to peace of mind, for your $10 you'll
  306. get the right to use this unit in your programs royalty free.  Please
  307. send international/postal money orders or a check drawn on a Canadian bank.
  308.  If you think you'd like to customize this unit for your application, if
  309. you send $30 (and specify media preference) I'll send you all current
  310. source code.
  311.  
  312.  Whether you decide to pony up this minor utilization fee or not, the
  313. author would appreciate any bug reports or suggestions that may
  314. be forthcoming.
  315.  
  316.  
  317.                           Douglas Webb
  318.                           228 Murray St.
  319.                           Montreal, Quebec
  320.                           H3C 2C7
  321.                           CANADA
  322.  
  323.  
  324. LEGAL DOGMA
  325. ___________
  326.  
  327.  
  328. Douglas Webb (hereafter refered to as 'the author') hereby disclaims all
  329. warranties relating to this software, whether express or implied,
  330. including without limitation any implied warranties of merchantability
  331. or fitness for a particular purpose.  The author will not be liable
  332. for any special, incidental, consequential, indirect or similar damages
  333. due to loss of data or any other reason, even if the author has been
  334. advised of the possibility of such damages.  The person using the software
  335. bears all risk as to the quality and performance of the software.
  336.  
  337. The author has done his very best to make sure that everything stated
  338. in above documentation is correct.  However, the author assumes no
  339. responsibility for errors that may appear in the descriptions of this
  340. software (although he would like to hear about them).
  341.  
  342.  
  343.  
  344. Turbo Pascal is a trademark of Borland International.
  345. QEMM-386 is a trademark of QuarterDeck Office Systems.
  346. 386^Max is a trademark of Qualitas Inc.
  347.  
  348.  
  349.  
  350. HISTORY
  351. -------
  352. Version 1.0
  353.  - ESPOOLER is sprung on an unsuspecting world.
  354.  
  355. Version 1.01
  356.  - Minor printing speed improvement.
  357.  
  358.  - Fixed bug which didn't allow you to close the spooler without turning
  359.     the printer on.  This is real annoying if you don't have a printer
  360.     attached.
  361.  
  362.  - Fixed bug in 'SPOOLERSTATUS' which caused divide by zero error when in
  363.     'Direct_To_Printer' mode.
  364.  
  365.  - Added code to allow a program using the spooler to load even if either:
  366.     a) There was insufficient heap for the default spooler buffer.
  367.     b) The spooler couldn't find the DOS CriticalStatus flag.
  368.  
  369. Version 1.1
  370.  - added the ability to use XMS
  371.  
  372.  - added run-time customizable priority setting which affects printing
  373.     speed (useful for high speed printers).
  374.  
  375.          ----------------end-of-author's-documentation---------------
  376.  
  377.                          Software Library Information:
  378.  
  379.                     This disk copy provided as a service of
  380.  
  381.                            Public (software) Library
  382.  
  383.          We are not the authors of this program, nor are we associated
  384.          with the author in any way other than as a distributor of the
  385.          program in accordance with the author's terms of distribution.
  386.  
  387.          Please direct shareware payments and specific questions about
  388.          this program to the author of the program, whose name appears
  389.          elsewhere in  this documentation. If you have trouble getting
  390.          in touch with the author,  we will do whatever we can to help
  391.          you with your questions. All programs have been tested and do
  392.          run.  To report problems,  please use the form that is in the
  393.          file PROBLEM.DOC on many of our disks or in other written for-
  394.          mat with screen printouts, if possible.  PsL cannot debug pro-
  395.          programs over the telephone, though we can answer questions.
  396.  
  397.          Disks in the PsL are updated  monthly,  so if you did not get
  398.          this disk directly from the PsL, you should be aware that the
  399.          files in this set may no longer be the current versions. Also,
  400.          if you got this disk from another vendor and are having prob-
  401.          lems,  be aware that  some files may have become corrupted or
  402.          lost by that vendor. Get a current, working disk from PsL.
  403.  
  404.          For a copy of the latest monthly software library newsletter
  405.          and a list of the 2,000+ disks in the library, call or write
  406.  
  407.                            Public (software) Library
  408.                                P.O.Box 35705 - F
  409.                             Houston, TX 77235-5705
  410.  
  411.                                 1-800-2424-PSL
  412.                              MC/Visa/AmEx/Discover
  413.  
  414.                           Outside of U.S. or in Texas
  415.                           or for general information,
  416.                               Call 1-713-524-6394
  417.  
  418.                           PsL also has an outstanding
  419.                           catalog for the Macintosh.
  420.  
  421.